打造專屬 ChatGPT：OpenAI Chat Completions API 實戰指南 (20260601更新)

如果你想自己打造一個類似 ChatGPT 的應用，OpenAI 的 Chat Completions API 是很常見的入門介面。

它的核心概念很簡單：你把一組 messages 傳給模型，模型根據這些對話內容產生下一則 assistant 回覆。

但當你真的要把它做成產品，就會開始遇到更多參數與情境，例如：

• 要用哪個 model
• messages 裡的 developer、user、assistant、tool role 怎麼設計
• 要如何調整 temperature、top_p、max_completion_tokens
• 要如何讓模型輸出 JSON 或符合 JSON Schema 的資料
• 要如何讓模型呼叫後端工具或內部 API
• 要如何做 streaming 串流回應
• 要如何記錄 token usage、metadata、user 與 request log
• 舊版 max_tokens、functions、function_call 應該怎麼遷移

原本我把這些內容整理在同一篇文章中，但後來發現篇幅太長，不利於閱讀與維護。因此這次將內容拆成三篇系列文，分別介紹基礎參數、進階功能，以及正式產品中的回傳物件、除錯與實務設定。

這篇文章則作為系列總覽與快速查找入口。

系列文章目錄

https://www.alfred.wiki/ai-gpt/custom-chatgpt-chat-completions-api-basics/

https://www.alfred.wiki/ai-gpt/custom-chatgpt-structured-outputs-tool-calling-streaming/

https://www.alfred.wiki/ai-gpt/custom-chatgpt-chat-completions-api-response-debugging-practice/

延伸閱讀：從 Chat Completions 轉向 Responses API

如果你是第一次接觸 OpenAI API，先理解 Chat Completions API 仍然很有價值，因為它能幫助你掌握 messages、roles、Tool Calling、Streaming、Structured Outputs 等核心概念。

不過，如果你現在要從零開始建立新的 OpenAI API 功能，也建議進一步了解 Responses API。Responses API 更像是 OpenAI API 新一代的統一入口，將 input、output、tools、structured output、streaming、多模態與 conversation state 整合在同一個 response workflow 中。

延伸文章：

https://www.alfred.wiki/ai-gpt/custom-chatgpt-responses-api-vs-chat-completions/

快速查找：你應該看哪一篇？

如果你是第一次接觸 Chat Completions API，建議先看第一篇。

如果你已經會發出基本請求，但想讓模型輸出 JSON、呼叫工具或支援 streaming，建議看第二篇。

如果你正在把功能放進正式產品，想處理 usage、metadata、log、回傳物件、除錯與舊參數遷移，建議看第三篇。

可以用這張表快速判斷：

Chat Completions API 參數快查表

下面是這個系列中會介紹的主要參數與用途。

最小可用範例

如果只是要發出一個最基本的 Chat Completion 請求，可以這樣寫：

from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "user",
            "content": "請用一句話解釋 Chat Completions API 是什麼。"
        }
    ],
)

print(completion.choices[0].message.content)

這個範例中最重要的是兩個參數：

• model：指定要使用哪個模型。
• messages：指定模型要根據哪些對話內容產生回覆。

更完整的基礎說明，可以閱讀第一篇：

打造專屬 ChatGPT（一）：Chat Completions API 基礎參數解析

什麼時候需要 response_format？

如果模型輸出是給人閱讀，通常可以使用一般文字輸出。

但如果模型輸出要交給程式解析，例如寫入資料庫、產生 API response、更新前端 UI 或建立後端流程，就建議使用 response_format。

常見選擇：

更完整的說明可以閱讀第二篇：

打造專屬 ChatGPT（二）：結構化輸出、Tool Calling 與 Streaming

什麼時候需要 Tool Calling？

如果模型只需要根據使用者輸入回答，通常不需要 Tool Calling。

但如果模型需要查詢外部資料或執行後端邏輯，就可以使用 Tool Calling。

例如：

• 查詢訂單狀態
• 查詢旅程花費
• 查詢資料庫
• 呼叫內部 API
• 建立行事曆事件
• 取得即時資料
• 執行計算或格式轉換

Tool Calling 的核心觀念是：

模型不會真的執行工具。
模型只會產生工具呼叫請求，真正執行工具的是你的後端程式。

因此正式產品中一定要做：

• 參數驗證
• 權限檢查
• 錯誤處理
• 高風險操作的使用者確認

完整流程可以閱讀第二篇。

什麼時候需要 Streaming？

如果你正在做聊天 UI，通常會需要 streaming。

非串流模式下，模型會產生完整回答後才一次回傳。
串流模式下，模型會一段一段回傳文字，使用者可以即時看到內容出現。

串流適合：

• 聊天 UI
• 長文生成
• 即時客服回答
• 使用者正在等待的互動流程

串流不一定適合：

• 批次摘要
• 資料抽取
• 分類任務
• 後台背景工作
• 需要完整 JSON 後再處理的流程

更完整的 stream、stream_options.include_usage 與 chat.completion.chunk 說明，可以閱讀第二篇與第三篇。

正式產品要注意什麼？

如果只是寫 demo，能拿到模型回答就可以了。

但如果要放進正式產品，還需要考慮：

• token usage 與成本
• latency
• request log
• user tracking
• metadata
• prompt version
• service tier
• finish reason
• error handling
• streaming 中斷
• tool calling 錯誤
• deprecated 參數遷移

至少建議記錄：

這些內容可以閱讀第三篇：

打造專屬 ChatGPT（三）：回傳物件、除錯與實務設定

新舊參數對照

如果你看過舊版 Chat Completions API 教學，可能會看到一些 legacy 寫法。

新專案建議使用較新的參數名稱與流程：

舊寫法仍然值得理解，因為你可能會維護舊專案或閱讀舊文章。
但如果是新專案，建議以目前官方文件與新的 SDK 寫法為準。

結語

Chat Completions API 看起來只是「傳入 messages，取得 assistant 回覆」，但真正做成產品時，它其實是一組可以控制模型行為的參數系統。

你可以用：

• messages 設計上下文
• temperature 控制生成風格
• response_format 取得結構化資料
• tools 接上外部系統
• stream 改善聊天體驗
• metadata 與 usage 做產品追蹤
• logprobs、seed、system_fingerprint 做除錯與分析

這個系列會從基礎到進階，再到正式產品維護，逐步整理 Chat Completions API 的主要參數與實務用法。

如果你是第一次接觸，建議從第一篇開始。
如果你已經有基本經驗，可以依照需求直接跳到第二篇或第三篇。
如果你已經看完 Chat Completions API 三篇系列，下一步可以閱讀「打造專屬 ChatGPT：從 Chat Completions 轉向 Responses API」，了解新專案為什麼可以優先考慮 Responses API，以及既有 Chat Completions 專案該如何分階段遷移。

打造專屬 ChatGPT：從 Chat Completions API 到產品實作 (20260601更新)

相關主題